<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>fielddata | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="mapping-params.html" title="Mapping parameters">
<link rel="prev" href="enabled.html" title="enabled">
<link rel="next" href="mapping-date-format.html" title="format">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="mapping.html">Mapping</a></span>
»
<span class="breadcrumb-link"><a href="mapping-params.html">Mapping parameters</a></span>
»
<span class="breadcrumb-node"><code class="literal">fielddata</code></span>
</div>
<div class="navheader">
<span class="prev">
<a href="enabled.html">« <code class="literal">enabled</code></a>
</span>
<span class="next">
<a href="mapping-date-format.html"><code class="literal">format</code> »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="fielddata"></a><code class="literal">fielddata</code><a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/params/fielddata.asciidoc">edit</a>
</h2>
</div></div></div>
<p>Most fields are <a class="xref" href="mapping-index.html" title="index">indexed</a> by default, which makes them
searchable. Sorting, aggregations, and accessing field values in scripts,
however, requires a different access pattern from search.</p>
<p>Search needs to answer the question <em>"Which documents contain this term?"</em>,
while sorting and aggregations need to answer a different question: <em>"What is
the value of this field for <span class="strong strong"><strong>this</strong></span> document?"</em>.</p>
<p>Most fields can use index-time, on-disk <a class="xref" href="doc-values.html" title="doc_values"><code class="literal">doc_values</code></a> for this
data access pattern, but <a class="xref" href="text.html" title="Text datatype"><code class="literal">text</code></a> fields do not support <code class="literal">doc_values</code>.</p>
<p>Instead, <code class="literal">text</code> fields use a query-time <span class="strong strong"><strong>in-memory</strong></span> data structure called
<code class="literal">fielddata</code>.  This data structure is built on demand the first time that a
field is used for aggregations, sorting, or in a script.  It is built by
reading the entire inverted index for each segment from disk, inverting the
term ↔︎ document relationship, and storing the result in memory, in the JVM
heap.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="fielddata-disabled-text-fields"></a>Fielddata is disabled on <code class="literal">text</code> fields by default<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/params/fielddata.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Fielddata can consume a <span class="strong strong"><strong>lot</strong></span> of heap space, especially when loading high
cardinality <code class="literal">text</code> fields.  Once fielddata has been loaded into the heap, it
remains there for the lifetime of the segment. Also, loading fielddata is an
expensive process which can cause users to experience latency hits.  This is
why fielddata is disabled by default.</p>
<p>If you try to sort, aggregate, or access values from a script on a <code class="literal">text</code>
field, you will see this exception:</p>
<pre class="literallayout">Fielddata is disabled on text fields by default.  Set `fielddata=true` on
[`your_field_name`] in order to load  fielddata in memory by uninverting the
inverted index. Note that this can however use significant memory.</pre>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="before-enabling-fielddata"></a>Before enabling fielddata<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/params/fielddata.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Before you enable fielddata, consider why you are using a <code class="literal">text</code> field for
aggregations, sorting, or in a script.  It usually doesn’t make sense to do
so.</p>
<p>A text field is analyzed before indexing so that a value like
<code class="literal">New York</code> can be found by searching for <code class="literal">new</code> or for <code class="literal">york</code>.  A <code class="literal">terms</code>
aggregation on this field will return a <code class="literal">new</code> bucket and a <code class="literal">york</code> bucket, when
you probably want a single bucket called <code class="literal">New York</code>.</p>
<p>Instead, you should have a <code class="literal">text</code> field for full text searches, and an
unanalyzed <a class="xref" href="keyword.html" title="Keyword datatype"><code class="literal">keyword</code></a> field with <a class="xref" href="doc-values.html" title="doc_values"><code class="literal">doc_values</code></a>
enabled for aggregations, as follows:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT my_index
{
  "mappings": {
    "properties": {
      "my_field": { <a id="CO343-1"></a><i class="conum" data-value="1"></i>
        "type": "text",
        "fields": {
          "keyword": { <a id="CO343-2"></a><i class="conum" data-value="2"></i>
            "type": "keyword"
          }
        }
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/757.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO343-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Use the <code class="literal">my_field</code> field for searches.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO343-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Use the <code class="literal">my_field.keyword</code> field for aggregations, sorting, or in scripts.</p>
</td>
</tr>
</table>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="enable-fielddata-text-fields"></a>Enabling fielddata on <code class="literal">text</code> fields<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/params/fielddata.asciidoc">edit</a>
</h3>
</div></div></div>
<p>You can enable fielddata on an existing <code class="literal">text</code> field using the
<a class="xref" href="indices-put-mapping.html" title="Put mapping API">PUT mapping API</a> as follows:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT my_index/_mapping
{
  "properties": {
    "my_field": { <a id="CO344-1"></a><i class="conum" data-value="1"></i>
      "type":     "text",
      "fielddata": true
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/758.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO344-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The mapping that you specify for <code class="literal">my_field</code> should consist of the existing
mapping for that field, plus the <code class="literal">fielddata</code> parameter.</p>
</td>
</tr>
</table>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="field-data-filtering"></a><code class="literal">fielddata_frequency_filter</code><a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/params/fielddata.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Fielddata filtering can be used to reduce the number of terms loaded into
memory, and thus reduce memory usage. Terms can be filtered by <em>frequency</em>:</p>
<p>The frequency filter allows you to only load terms whose document frequency falls
between a <code class="literal">min</code> and <code class="literal">max</code> value, which can be expressed an absolute
number (when the number is bigger than 1.0) or as a percentage
(eg <code class="literal">0.01</code> is <code class="literal">1%</code> and <code class="literal">1.0</code> is <code class="literal">100%</code>). Frequency is calculated
<span class="strong strong"><strong>per segment</strong></span>. Percentages are based on the number of docs which have a
value for the field, as opposed to all docs in the segment.</p>
<p>Small segments can be excluded completely by specifying the minimum
number of docs that the segment should contain with <code class="literal">min_segment_size</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT my_index
{
  "mappings": {
    "properties": {
      "tag": {
        "type": "text",
        "fielddata": true,
        "fielddata_frequency_filter": {
          "min": 0.001,
          "max": 0.1,
          "min_segment_size": 500
        }
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/759.console"></div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="enabled.html">« <code class="literal">enabled</code></a>
</span>
<span class="next">
<a href="mapping-date-format.html"><code class="literal">format</code> »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
